什麼是 Eloquent？

Eloquent 是 Laravel 提供的 ORM（Object-Relational Mapping）工具，讓我們能夠以「物件導向」的方式來操作資料庫。

你可以把 Eloquent 理解為：

Laravel 將每個資料表對應到一個 Model 類別，並提供一套簡潔的 API 來進行資料的新增、查詢、更新、刪除（CRUD）與關聯操作。

基本用法：查詢資料

舉例：

use App\Models\User;

$users = User::where('name', 'Demo Wang')->get();

上述語法會自動轉換成 SQL：
SELECT * FROM users WHERE name = 'Demo Wang';

而返回的 $users 是一個包含 User 實例的集合（Collection）。

常見的 Eloquent 方法

方法說明get()取得查詢結果（回傳 Collection）first()取得第一筆結果（回傳單一 Model 或 null）find($id)依主鍵尋找資料create([...])建立新資料update([...])更新資料（配合查詢條件）delete()刪除資料

關聯（Relationships）

Laravel Eloquent 提供多種資料表之間的關聯對應，例如：

• 一對一（One To One）
• 一對多（One To Many）
• 多對多（Many To Many）
• 多型關聯（Polymorphic）
• 一對一關聯：hasOne / belongsTo

User 與 Phone：一人一手機

// User.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasOne;
class User extends Model
{
    public function phone(): HasOne
    {
        return $this->hasOne(Phone::class);
    }
}

預設會將 User.id 對應到 Phone.user_id。

若要自訂欄位名稱：

return $this->hasOne(Phone::class, 'foreign_key', 'local_key');

Phone 屬於 User：

// Phone.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
class Phone extends Model
{
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

這表示 Phone.user_id 是外鍵，指向 User.id。

使用方式

取得使用者手機：

$user = User::find(1);
$phone = $user->phone;

取得手機擁有者：

$phone = Phone::find(1);
$user = $phone->user;

Laravel 會根據你在 Model 中定義的關聯，自動查出資料。

補充

使用 with() 可以預載入關聯，避免 N+1 問題：
$users = User::with('phone')->get();
如果關聯欄位名稱不是 Laravel 預設的 user_id，記得要手動指定 foreign_key 和 local_key
關聯的回傳型別（如 HasOne、BelongsTo）是 PHPStan / IDE 輔助，非必要，但加上可提升可讀性

總結

功能方法補充說明一對一關聯hasOne在主表（例如 User）中定義一對一反向關聯belongsTo在從表（例如 Phone）中定義資料查詢where、get() 等透過 Model 直接查詢資料操作create()、update()、delete()與資料表資料互動

🔗 更多的 Eloquent 方法與關聯類型，請參考 Laravel 官方文件